<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Strict//EN">
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<title>DRAG AND DROP</title>

<link rel="stylesheet" type="text/css" href="../../style.css">
<style type="text/css">
.style9 {
	font-size: large;
}
.auto-style1 {
	font-weight: normal;
}
.style10 {
	font-size: medium;
}
</style>
</head>
<body>

<h2>DRAG &amp; DROP<span class="style9"> (since 3.6)</span></h2>
<p>When enabled allow the use of callbacks for controlling the drag and drop 
handling.</p>
<p>The user starts a drag 
and drop transfer by pressing the mouse button over the data (Windows and GTK: left 
button; Motif: middle button) which is referred to as the 
drag source. The data can be dropped in any location that has been registered as 
a drop target. The drop occurs when the user releases the mouse button. This can 
be done inside a control, from one control to another in the same dialog, in 
different dialogs of the same application, or between different applications 
(the other application does NOT need to be implemented with IUP).</p>
<p>In IUP, a drag and drop transfer can result in the data being moved or 
copied. A <strong>copy</strong> operation is enabled with the CTRL key 
pressed. A <strong>move</strong> operation is enabled with the SHIFT key 
pressed. A move operation will be possible only if the attribute DRAGSOURCEMOVE is 
Yes. When no key is pressed the default operation is <strong>copy</strong> when 
DRAGSOURCEMOVE=No and <strong>move</strong> when DRAGSOURCEMOVE=Yes. The user can cancel 
a drag at any time by pressing the ESCAPE key.</p>
<p>Steps to use the Drag &amp; Drop support in an IUP 
application:</p>
<ul>
	<li><strong>AT SOURCE:</strong><ul>
		<li>Enable the element as source using the attribute DRAGSOURCE=YES;</li>
		<li>Define the data types supported by the element for the drag 
		operation using the DRAGTYPES attribute;</li>
		<li>Register the required callbacks DRAGBEGIN_CB, DRAGDATASIZE_CB and 
		DRAGDATA_CB for drag handling. DRAGEND_CB is the only optional drag callback, 
		all other callbacks and attributes must be set.</li>
	</ul>
	</li>
	<li><strong>AT TARGET:</strong><ul>
		<li>Enable the element as target using the attribute DROPTARGET=YES;</li>
		<li>Define the data types supported by the element for the drop using 
		the DROPTYPES attribute;</li>
		<li>Register the required callback DROPDATA_CB for handling the data 
		received. This callback and all the drop target attributes must be set 
		too. DROPMOTION_CB is the only optional drop callback.</li>
	</ul>
	</li>
</ul>
<h3>Affects</h3>
<p><a href="../elem/iuplabel.html">IupLabel</a>, <a href="../elem/iuptext.html">IupText</a>, <a href="../elem/iuplist.html">IupList</a>,
<a href="../elem/iuptree.html">IupTree</a>, <a href="../elem/iupcanvas.html">IupCanvas</a> and
<a href="../dlg/iupdialog.html">IupDialog</a>. </p>

<h3>Attributes at Drag Source</h3>

<p><strong>DRAGC</strong><span class="auto-style1"><strong>URSOR (non inheritable):</strong> 
name of an image to be used as cursor during drag. Use
	<a href="../func/iupsethandle.html">IupSetHandle</a> or
	<a href="../func/iupsetattributehandle.html">IupSetAttributeHandle</a> to 
	associate an image to a name. See also
	<a href="../elem/iupimage.html">IupImage</a>. (since 3.11)</span></p>
<p><strong>DRAGSOURCE</strong><span class="auto-style1"><strong> (non inheritable):</strong> </span>Set up a control as a source for drag operations. Default: NO.</p>
<p><strong>DRAGTYPES</strong><span class="auto-style1"><strong> (non inheritable):</strong> </span>A list of data types that are supported 
by the source. Accepts a string with one or more names separated by commas.
 See <a href="#Notes">Notes</a> bellow for a list of known names. Must be set.</p>
<p><strong>DRAGSOURCEMOVE (non inheritable)</strong>: Enables the move action. 
Default: NO (only copy is enabled).</p>

<h3>Attributes at Drop Target</h3>

<p><strong>DROPTARGET</strong><span class="auto-style1"><strong> (non inheritable)</strong>: </span> Set up a control as a destination for drop operations. Default: NO.</p>
<p><strong>DROPTYPES (non inheritable)</strong>: A list of data types that are supported 
by the target. Accepts a string with one or more names separated by 
commas. See <a href="#Notes">Notes</a> bellow for a list of known names. Must be 
set.</p>

<h3>Callbacks at Drag Source <span class="style10">(Must be set when DRAGSOURCE<span class="auto-style1">=Yes</span>)</span></h3>


<p><b>DRAGBEGIN_CB</b>: notifies source that drag started. It is called when the 
mouse starts a drag operation.</p>

  
    
<pre>int function(Ihandle*<strong> ih</strong>, int <strong>x</strong>, int <strong>y</strong>) [in C]<br><strong>elem</strong>:dragbegin_cb(<strong>x</strong>, <strong>y</strong>: number) -&gt; (<strong>ret</strong>: number) [in Lua]</pre>

    
<p class="info"><strong>ih</strong>:
  identifier of the element that activated the 
  event.<br><strong>x, y</strong>: cursor position relative to the top-left 
corner of the element.</p>

<p class="info"><u>Returns</u>: If IUP_IGNORE is returned the drag is 
aborted.</p>

  
<p><b>DRAGDATASIZE_CB</b>: request for size of drag data from source. It is 
called when the data is dropped, before the <b>DRAGDATA_CB</b> callback.</p>

  
    
<pre>int function(Ihandle*<strong> ih</strong>, char* <strong>type</strong>) [in C]<br><strong>elem</strong>:dragdatasize_cb(<strong>type</strong>: string) -&gt; (<strong>ret</strong>: number) [in Lua]</pre>

    
<p class="info"><strong>ih</strong>:
  identifier of the element that activated the 
  event.<br><strong>type</strong>: type of the data. It is one of the registered 
types in <strong>DRAGTYPES</strong><span class="auto-style1">.</span></p>

<p class="info"><u>Returns</u>: the size in bytes for the data. It will be used 
to 
allocate the buffer size for the data in transfer.</p>

  
<p><b>DRAGDATA_CB</b>: request for drag data from source. It is called when the 
data is dropped.</p>

  
    
<pre>int function(Ihandle*<strong> ih</strong>, char* <strong>type</strong>, void* <strong>data</strong>, int <strong>size</strong>) [in C]<br><strong>elem</strong>:dragdata_cb(<strong>type</strong>: string,<strong> data: </strong>userdata <strong>size</strong>: number) -&gt; (<strong>ret</strong>: number) [in Lua]</pre>

    
<p class="info"><strong>ih</strong>:
  identifier of the element that activated the 
  event.<br><strong>type</strong>: type of the data. It is one of the registered 
types in <strong>DRAGTYPES</strong><span class="auto-style1">.</span><br><strong>data</strong>: 
buffer to be filled by the application. In Lua is a light userdata. If your data 
is a string you can use iup.<strong>CopyString2UserData</strong>(str, data, 
size) to copy the string into the user data (since 3.27).<br><strong>size</strong>: buffer size in 
bytes. 
The same value returned by <b>DRAGDATASIZE_CB.</b></p>

  
<p><b>DRAGEND_CB</b>: notifies source that drag is done. The only drag callback that 
is <strong>optional</strong>. It is called after the data has been dropped.</p>

  
    
<pre>int function(Ihandle*<strong> ih</strong>, int <strong>action</strong>) [in C]<br><strong>elem</strong>:dragend_cb(<strong>action</strong>: number) -&gt; (<strong>ret</strong>: number) [in Lua]</pre>

    
<p class="info"><strong>ih</strong>:
  identifier of the element that activated the 
  event.<br><strong>action</strong>: action performed by the operation (1 = move, 
0 = copy, -1 = drag failed or aborted)</p>
<p class="info">If action is 1 it is responsibility of the application to remove 
the data from source.</p>

  
<h3>Callbacks at Drop Target <span class="style10">(Must be set when DROPTARGET=Yes)</span></h3>


<p><b>DROPDATA_CB</b>: source has sent target the requested data. It is called 
when the data is dropped. If both drag and drop would be in the same application 
it would be called after the <b>DRAGDATA_CB</b> callback.</p>

  
    
<pre>int function(Ihandle*<strong> ih</strong>, char* <strong>type</strong>, void* <strong>data</strong>, int <strong>size</strong>, int <strong>x</strong>, int <strong>y</strong>) [in C]<br><strong>elem</strong>:dropdata_cb(<strong>type</strong>: string, <strong>data</strong>: userdata, <strong>size, x, y</strong>: number) -&gt; (<strong>ret</strong>: number) [in Lua]</pre>

    
<p class="info"><strong>ih</strong>:
  identifier of the element that activated the 
  event.<br>
<strong>type</strong>: type of the data. It is one of the registered 
types in <strong>DROPTYPES</strong><span class="auto-style1">.</span><br>
<strong>data</strong>: content data received in the drop operation.&nbsp; In Lua 
is a light userdata. If your data is a string you can use &quot;str = iup.<strong>CopyUserData2String</strong>(data, 
size)&quot; to copy the user data into a string (since 3.27).<br>
<strong>size</strong>: data size in bytes.<br><strong>x, y</strong>: cursor position relative to the top-left 
corner of the element.</p>


<p><b>DROPMOTION_CB</b>: notifies destination about drag pointer motion. The 
only drop 
callback that is <strong>optional</strong>. It is called when the mouse moves over 
any valid drop site.</p>

  
    
<pre>int function(Ihandle *<strong>ih</strong>, int <strong>x</strong>, int <strong>y</strong>, char *<strong>status</strong>); [in C]
<strong>elem</strong>:dropmotion_cb(<strong>x</strong>, <strong>y</strong>: number, <strong>status</strong>: string) -&gt; (<strong>ret</strong>: number) [in Lua]</pre>

    
<p class="info"><strong>ih</strong>: identifier of the element that activated 
the event.<br><strong>x</strong>, <strong>y</strong>: position in the canvas 
where the event has occurred, in pixels.<br><strong>status</strong>: status of 
mouse buttons and certain keyboard keys at the moment the event was generated. 
The same macros used for <a href="../call/iup_button_cb.html">BUTTON_CB</a> can 
be used for this status.</p>

  
<h3><a name="Notes">Notes</a></h3>

<p>Drag and Drop support can be set independently. A control can have drop 
without drag support and vice-versa.</p>
<p>Here are some common Drag&amp;Drop types defined by existing applications:</p>
<ul>
	<li>&quot;TEXT&quot; used for regular text without formatting. Automatically 
	translated to CF_TEXT in Windows.</li>
	<li>content MIME types, like &quot;text/uri-list", 
"text/html", "image/png", "image/jpeg", "image/bmp" and "image/gif".</li>
	<li>&quot;UTF8_STRING&quot; in GTK and &quot;UNICODETEXT&quot; in Windows.</li>
	<li>&quot;COMPOUND_TEXT&quot; in GTK and &quot;Rich Text Format&quot; in Windows.</li>
	<li>&quot;BITMAP&quot; and &quot;DIB&quot; in Windows. Automatically translated to CF_BITMAP and 
	CF_DIB.</li>
</ul>

  
<h3>Examples</h3>
<p><a href="../../examples/C/list2.c">list2.c</a></p>
</body>

</html>
